home *** CD-ROM | disk | FTP | other *** search
/ Language/OS - Multiplatform Resource Library / LANGUAGE OS.iso / gnu / amiga / gcc21920.lha / README < prev   
Text File  |  1992-04-20  |  17KB  |  400 lines
  1. First the legal stuff:
  2.  
  3. This archive contains two independant parts, one consists of the binaries
  4. for the GNU C compiler V2.1, those files are all in the `gcc20' tree, and
  5. are subject to the license specified in the COPYING file.
  6.  
  7. The other part consists of new versions for my shared C library and the
  8. link level counterparts.  Those files are subject to the COPYING.LIB file.
  9.  
  10. You can get the full distribution for gcc2.1 for example from
  11. prep.ai.mit.edu, the source for the library is available for example from
  12. amiga.physik.unizh.ch.
  13.  
  14. -----------------------------------------------------------------------------
  15.  
  16. A special note to the library: I'm currently changing the library sources
  17. to finally adapt more closely to the BSD-net2 distribution. As a goal, this
  18. library should then also support networking, starting with AF_UNIX sockets
  19. and pipes implemented ala socketpair(). The library that is included in libs/
  20. is a mixture between old and new code, I can therefore not distribute any
  21. sources until the library has been changed completely. The reason I'm
  22. including this version is that I'd like to get feedback whether the new
  23. way to deal with packets that this library uses causes problems on some
  24. Amigas. So if you find this library to cause problems (crashes, other weird
  25. things), *AND THE PREVIOUS VERSION WORKED*, please tell me, I'd very much
  26. like to get rid of such problems before the next version is released.
  27.  
  28. You might notice that the startup code changed, this is to allow full
  29. implementation of execve() and friends, thus to actually pass an argument
  30. vector instead of a commandline to started programs. vfork() is there
  31. as well as wait4() and friends.  You may try your luck on those new
  32. functions, but keep in mind that *they are not supported* at the moment.
  33. There are problems with vfork() that I'll fix in the next release, but I'll
  34. have to include support for process groups to do it `right', currently you
  35. cannot ^C break any children spawned with vfork() with the keyboard, BREAK
  36. works though.  An other problem exists with pipe():  if you break a reader,
  37. the pipe might hang and you're not able to kill the writer.  This will be
  38. fixed by using sockets and sending the apropriate SIGPIPE to the writer
  39. (the problem is permanent under 1.3, the 2.0 pipe is lots smarter, but not
  40. yet perfect ;-)).
  41.  
  42. To repeat the important information:  the functions are there, but unless
  43. you know what you do, don't use them, not all problems are solved in this
  44. library release!
  45.  
  46. -----------------------------------------------------------------------------
  47.  
  48.  
  49. INSTALLATION
  50.  
  51. This distribution only contains the compilers and changed parts of my C
  52. library.  If you don't have a C library yet, you'll have to get one to be
  53. able to compile C programs.  You can either get my library (get
  54. ixemlib9203.lha but use *THIS* ixemul.library in libs/ !!) or use another C
  55. library you might already have.  If you're not using my library, here's
  56. what you have to do in short form:
  57.   o  create a directory, assign GCC: to it
  58.   o  create a directory called gcc:lib, here go your crt0.o and libc.a files
  59.   o  create a directory called gcc:include, that's where your headers go
  60. The ixemlib9203.lha archive contains a Readme that explains this setup
  61. in greater detail).
  62.  
  63. The distribution contains 3 directories:
  64.   gcc20        - this contains stuff for gcc
  65.   gcc        - this contains updates for the gcc: tree if you use my library
  66.   libs        - this contains ixemul.library, which is used by gcc, and
  67.             which you have to copy to your LIBS: directory. This library
  68.             overrides all previous versions, please replace any older
  69.             copy!
  70.  
  71. To install gcc, you just have to assign GCC20: to gcc20/, ie. the directory
  72. tree called gcc20/ that you created by unpacking this archive.
  73.  
  74. Then add gcc20:bin to your PATH, and you're finished installing gcc, it can
  75. then be used like `gcc hello-world.c'.
  76.  
  77. *Be sure to use a large enough STACK setting! I'm using a STACK 250000 myself,
  78. *and this worked even for the weirdest programs. You *will* crash the machine
  79. *or get the weirdest errors if you use the Commodore default of 4k !!!!
  80.  
  81. The stuff in gcc/ should be copied to the apropriate place in your gcc:
  82. tree, it gives you a newer startup code (that now passes DOSBase and
  83. SysBase to your programs), and a newer libc.a (see the comments at the
  84. begin as well for comments to this version of the library).
  85.  
  86. Repeating myself, copy libs/ixemul.library to LIBS: !
  87.  
  88. Read the original manuals as well: read the info* file in the info
  89. directory.  NOTE:  the info files are not complete!  I didn't include any
  90. files that describe compiler interna, as they are not of interest to the
  91. majority of users that don't plan to change gcc itself.  If you want the
  92. complete manual, get the whole distribution from (for example)
  93. prep.ai.mit.edu! Second remark for 2.1: the provided info files are from
  94. gcc2, since only interna changed, this is still a valid manual.
  95.  
  96. As a side effect of ixemul.library now converting paths like `/usr/include'
  97. into `usr:include', you get requesters like `Please insert volume usr:'.
  98. You can get rid of them by assigning a dummy directory to them. (You
  99. could as well build a **IX tree, and place your stuff there). Candidats
  100. for dummy-assigns are:
  101.  
  102.   tmp:    usr:    etc:    lib:    local:    dev:
  103.  
  104. As long as you don't want them to represent something useful, just make
  105. sure the assigns exist, and you won't be nerved by those requesters.
  106.  
  107.  
  108. HOW TO CALL THE C++ COMPILER 
  109.  
  110. The Unix copy of gcc comes with a shell script, that emulates `gpp' in
  111. its behavior to even call the C++ compiler on `*.c' files.  Either call
  112. your C++ files `*.cc' (the preferred solution), or call the C++ compiler
  113. explicitly by using the `-x c++' switch to the compiler.  The Unix `c++'
  114. script includes `-lg++' by default, you have to do this explicitly when
  115. calling gcc directly. 
  116.  
  117. If you have AREXX installed in your system, you might as well use the
  118. two AREXX commands provided by Loren J. Rittle (thanks Loren !), they
  119. are in the rexx/ directory. Read them, they include instructions.
  120.  
  121.  
  122.  
  123. COEXISTANCE OF GCC 2.1 with GCC 1.40 & G++ 1.40
  124.  
  125. If you want to use the older compiler as well, all you have to do is to
  126. rename gcc20:bin/gcc to gcc20:bin/gcc2, then you can use `gcc' and `gpp' as
  127. usual to refer to the 1.40 compilers, and `gcc2' to refer to gcc2.1.  You
  128. might as well update some programs of 1.40:
  129.   copy gcc20:lib/gcc-lib/amiga/2.1/as local:gcc-as
  130.   copy gcc20:lib/gcc-lib/amiga/2.1/ld local:gcc-ld
  131. Don't copy cpp over though, cpp depends on the compiler version !
  132.  
  133. If you're using g++-1.40 and the C++ compiler of gcc-2.1 concurrently, you'll
  134. probably only want to keep one copy of C++ header files. G++ 1.40 expects to
  135. find them under
  136.   LOCAL:g++-include
  137. but gcc-2.0 looks for them in
  138.   GCC20:lib/g++-include
  139. To fix this, you can either make a symbolic link to where you keep your
  140. C++ headers, or you can use the following directory tree:
  141.   GCC20: -> <the base directory of your gcc20 tree>
  142.   LOCAL: -> GCC20:lib
  143.                /gcc-cpp    }
  144.                /gcc-cc1    } 
  145.                /gcc-cc1plus } these are the 1.40 compilers
  146.                /gcc-as    }
  147.                /gcc-ld    }
  148.                /g++-include  C++ headers for both, 1.40 and 2.1
  149.  
  150.              /gcc-lib/amiga/2.1
  151.                     /specs       2.1 command template
  152.                                     /cpp    }
  153.                                      /cc1    }
  154.                             /cc1plus}  these are the 2.1 compilers
  155.                     /cc1obj    }
  156.                            /as    }
  157.                     /ld    }
  158.  
  159. I'd recommend you switch to gcc 2, as I won't support the 1 release any
  160. longer. With the new resident capability (see below) of gcc 2, less memory
  161. is needed to fire up release 2 compilers.
  162.  
  163.  
  164. DISK LAYOUT DIFFERENCES TO GCC 2.0
  165.  
  166. There are several differences. One you probably just noticed, the directory
  167. structure changed again (sorry), mainly because gcc20: really stands for
  168. the **IX /usr/local directory, and people wanted to have gcc specific stuff
  169. not just in /usr/local/gcc, but in /usr/local/gcc-lib. Another difference:
  170. The compilers are now in the target dependant directory (amiga/2.1), not
  171. in the base directory (I might have done that wrong in 2.0 myself..).
  172. So if you used 2.0, make sure to rename the gcc20:lib/gcc into 
  173. gcc20:lib/gcc-lib, and to delete the compilers in the gcc20:lib/gcc 
  174. directory.
  175.  
  176.  
  177.  
  178. AMIGA SPECIFIC CHANGES, NEW FOR 2.1
  179.  
  180. The most important change in 2.1 is that gcc finally can generate base
  181. relative code (which means, that it addresses the data/bss segment by
  182. indirection on A4). Based on base relative code, it is as well possible to
  183. generate `pure' programs, ie. programs you can set the PURE bit on with
  184. the PROTECT command, and then make them resident with the RESIDENT command.
  185.  
  186. Here's a short explanation for the new switches to gcc:
  187.  
  188.   Option    Explanation
  189.  
  190.   -fbaserel    generate base relative code (needed by cc1 and (!) ld)
  191.   -resident    generate base relative code, and link it in a way so
  192.           that it is `pure' (see above). -resident does the same as
  193.         -fbaserel in cc1, but does additional work in ld.
  194.   -msmall-code    generate 16bit BSRs instead of 32bit JSRs. This option
  195.           is only needed by as.
  196.  
  197. You may mix -msmall-code object files with normal object files. You
  198. may as well mix base relative code with non base relative code, provided
  199. that you specify -fbaserel to the linker. Don't (!) specify -resident
  200. in this case, since code which was not compiled base relative is not
  201. per se residentable with -resident!
  202.  
  203. *************************************************************************
  204. All executables in this distribution are new compiled with -resident, and
  205. are therefore RESIDENTable.
  206. Please don't use REZ anymore on them, REZ doesn't recognise that they're
  207. pure, and you'll lose the memory gains you get with RESIDENT.
  208. *************************************************************************
  209.  
  210. With the addition of these features, new libraries were needed as well. 
  211. Besides the `old' libraries (libc.a, libgcc.a, crt0.o), you get new base
  212. relative libraries (libbc.a, libbgcc.a, bcrt0.o), and a new startup
  213. file (rcrt0.o) used to startup pure executables.
  214.  
  215. Here comes a technical implementation section (indented after `t').
  216. Skip if you're not interested in those details.
  217.  
  218. t All the new support for base relative runtime support is in 2 new functions
  219. t in ixemul.library. Here's a short explanation on what they do:
  220. t 
  221. t   void ix_resident (int num_par, int a4, int databss_size, long *relocs);
  222. t 
  223. t This is the heart of the new functions. ix_resident() can be called
  224. t in different ways, depending on the level of support you need/want.
  225. t 
  226. t   ix_resident (2, __a4_init);
  227. t 
  228. t In this case, you get a plain base relative startup, the base
  229. t register (a4) is set to the value provided by the linker (the __a4_init
  230. t symbol).
  231. t 
  232. t   ix_resident (4, __a4_init, databss_size, relocs);
  233. t   
  234. t In this case, you provide enough information to ix_resident, so that
  235. t the data/bss segment can be relocated each time you call ix_resident().
  236. t This way, each fresh copy of the process gets a unique databss segment,
  237. t which makes the program pure. Please look at the bcrt0.c file to see
  238. t how to implement resident programs based on ix_resident() support.
  239.  
  240.  
  241. The second function provided is:
  242.  
  243.   void ix_geta4 (void);
  244.  
  245. This function (re)loads the base register. 
  246.  
  247. t Note:  this functions works even for resident programs!  Take care though,
  248. t that you don't refer to the base register calling this function, as would
  249. t happen if you just used the function as is (the glue functions use the
  250. t `ixemulbase' to jump into the library, and this variable is addressed using
  251. t a4 !).  Use the direct calling method instead (see the README file for
  252. t ixemul.library).  A future version of gcc will include support for setting
  253. t up the base register with a language extension (something like the SAS
  254. t __saveds attribute), until then, you're at your own.  Generally this
  255. t doesn't matter though, as you only need to (re)load the base register by
  256. t hand, if you start your own processes, and want them to use your globals as
  257. t well.
  258.  
  259.  
  260.  
  261. SOME FREQUENTLY ASKED QUESTIONS
  262.  
  263. Q: `I keep getting requesters saying, that mathieeesingbas.library couldn't
  264.     be opened. Does gcc not work under 1.3??'
  265. A: Gcc *does* work under 1.3, but it needs the single precision math libraries
  266.    to implement the C `float' data type. The mathieeesingbas.library is built
  267.    into ROM under Kick 2.04, but is needed as a file in LIBS: under Kick 1.3.
  268.    You have to ask your local Commodore support for this library, or if you're
  269.    lucky, you can get it from an (illegally.., not by myself!) posted article on 
  270.    comp.sys.amiga.programmers. If you didn't capture that article, perhaps
  271.    somebody else had, but DON'T ASK ME! I won't send you neither the libraries
  272.    nor the article in question!
  273.  
  274. Q: `I don't get any .o files, even though the assembler seems to be called 
  275.     correctly.'
  276. A: This problem should have vanished in the mean time. It resulted from using
  277.    a bogous copy of the assembler. Use the one provided in this release, and
  278.    the problem should go away.
  279.  
  280. Q: `Program <xy> that uses ixemul.library requests the LOCAL: drive, which
  281.     I don't have?!'
  282. A: ixemul.library searches LOCAL: for a timezone database. All you have to do
  283.    is assign LOCAL: to some existing directory, and the functions will be able
  284.    to determine that no such database exists. If you have gcc-1.40 installed,
  285.    you won't have this problem, as LOCAL: is used to find the compiler passes.
  286.  
  287. Q: `I keep getting a bus error using program <xy>, what's wrong?'
  288. A: Tell me which program generated that error. This is most certainly a program
  289.    that contains 68020 code and which you tried to run on a 68000 machine.
  290.    As long as the program is not specifically marked as `68020 only', this is
  291.    to be considered a bug!
  292.    Note that `bus error' can mean both, a m68k bus error exception or a m68k
  293.    address error exception. The signal model uses only one signal for both.
  294.    This error might as well fit into the next question, read on!
  295.  
  296. Q: `My machine always crashes when I try to use gcc, or I get weird error
  297.     messages like "bus error" or "illegal instruction". Sometimes I can
  298.     successfully compile, but the machine crashes soon afterwards, when I
  299.     execute programs that normally don't crash.'
  300. A: Did you set your STACK high enough? The Commodore default of 4k is WAYS too
  301.    low for GNU programs, I have my STACK at 250000, you might try lower
  302.    values, but I'd recommend not going below 100k !
  303.  
  304. Q: `I did "gcc -lg++ test.cc" and kept getting errors at link time'
  305. A: Supply the libraries AFTER the source/object files. 
  306.    Thus do `gcc test.cc -lg++' in this example. Don't forget to terminate
  307.    the command with a space, or AmigaDOS will swallow your last `+'.
  308.  
  309. Q: `Now that we have gcc release 2, can I remove my release 1 compilers?'
  310. A: Depends on what you're programming in mostly. If you're only interested in
  311.    the C compiler, you can remove the 1.40 gcc, no problem. If you're a C++
  312.    programmer though, I'd suggest (if you have the disk space) you keep your
  313.    1.40 g++, since the language definition changed slightly from 1.40 to
  314.    2.0, and the 2.0 C++ compiler seems buggier than the 1.40 one. The 2.0
  315.    C-compiler could demonstrate reliability by recompiling itself, the C++
  316.    didn't have a comparable chance. Use the 2.0 C++ compiler though! The C++
  317.    language implemented by gcc2.0 is richer than the 1.40 one, templates are
  318.    supported, ANSI exceptions, etc. By keeping the 1.40 compiler you just keep
  319.    the option of reverting to 1.40 in cases where you're not sure whether your
  320.    program or the compiler is buggy.
  321.    2.1 note: please use 2.1 and report bugs to GNU! 2.1 should have all known
  322.    2.0 bugs fixed, and C++ should be quite stable by now.
  323.    
  324. Q: `Although I don't define "alloca" to be "__builtin_alloca", gcc2 uses its
  325.     builtin function for it, what can I do?'
  326. A: Use the `-fno-builtin' switch.
  327.  
  328.  
  329.  
  330. EXAMPLE CONFIGURATION
  331.  
  332. Since getting gcc up and running seems to be harder than I thought (it does
  333. have some crap in it that can only be expained historically..), I provide you
  334. with my own setups, perhaps are examples more helpful than explanations...
  335.  
  336. s:user-startup
  337. --------------
  338. ...
  339. STACK 250000
  340. ASSIGN gcc:    dh4:mylibc
  341. ASSIGN gcc20:     dh4:gcc20-stuff
  342.  
  343. ; dummies
  344. ASSIGN tmp:     t:
  345. ASSIGN usr:    dh6:usr
  346. ASSIGN lib:    gcc:lib
  347. ASSIGN etc:    local:
  348.  
  349. RESIDENT gcc20:lib/gcc-lib/amiga/2.1/cpp
  350. RESIDENT gcc20:lib/gcc-lib/amiga/2.1/cc1
  351. ;I don't have those resident, because I use them too seldom
  352. ;RESIDENT gcc20:lib/gcc-lib/amiga/2.1/cc1plus
  353. ;RESIDENT gcc20:lib/gcc-lib/amiga/2.1/cc1obj
  354. RESIDENT gcc20:lib/gcc-lib/amiga/2.1/as
  355. RESIDENT gcc20:lib/gcc-lib/amiga/2.1/ld
  356. RESIDENT c:gcc2
  357.  
  358. dh4:mylibc/
  359. ----------
  360. contains (among other stuff):
  361.   dh4:mylibc/include    my header files
  362.   dh4:mylibc/lib    the libraries and startup files
  363.  
  364. dh4:gcc20-stuff/
  365. ---------------
  366. contains (among other stuff):
  367.   dh4:gcc20-stuff/bin:
  368.   gcc
  369.  
  370.   dh4:gcc20-stuff/info:
  371.   gcc-manual.lha
  372.  
  373.   dh4:gcc20-stuff/lib:
  374.   g++-include  gcc-lib
  375.  
  376.   dh4:gcc20-stuff/lib/gcc-lib:
  377.   amiga
  378.  
  379.   dh4:gcc20-stuff/lib/gcc-lib/amiga:
  380.   2.1
  381.  
  382.   dh4:gcc20-stuff/lib/gcc-lib/amiga/2.1:
  383.   SYSCALLS.c.X as      cc1        cc1obj        cc1plus
  384.   cpp           ld      libbgcc.a    libg++.a    libgcc.a      specs
  385.  
  386.  
  387.  
  388. FINALLY...
  389.  
  390. Good luck with this really great compiler. I'd like to thank all the wonderful
  391. guys that made this compiler what it is today, thank you! For the contributors
  392. to gcc, read the GNU CC manual!
  393.  
  394.  
  395. -Markus Wild
  396.  
  397. You can reach me as:
  398.  
  399. <wild@nessie.cs.id.ethz.ch> or as <wild@amiga.physik.unizh.ch>
  400.